PortionLine

PortionLine
Header:	QuickdrawText.h		Carbon status:	Supported

Determines the correct proportion of extra space to apply to the specified style run in a line of justified text; that is, how to distribute the total slop value for a line among the style runs on that line.

Fixed PortionLine (
    Ptr textPtr, 
    SInt32 textLen, 
    JustStyleCode styleRunPosition, 
    Point numer, 
    Point denom
);

textPtr

A pointer to the style run.

textLen

The number of bytes in the text of the style run.

styleRunPosition

The position on the line of this style run. The style run can be the only one on the line, the leftmost on the line, the rightmost on the line, or one between two other style runs.

This parameter specifies the position of the style run on the display line. It is used to determine the proportion of total slop to apply to a style run, measure or draw a line of justified text, identify where to break a line of text, and determine the caret position to mark an insertion point or highlight text.

The style run position parameter is meaningful only for those script systems that use intercharacter spacing for justification. For all other script systems, the parameter exists for future extensibility. Although the style run position parameter is not used, for example, for justifying text in the Roman script system, to allow for future compatibility, you should always specify the appropriate value for it for all calls that take it.

For those script systems that do use intercharacter spacing, space between style runs may be allocated differently depending upon whether the style run is leftmost, rightmost, or between two other style runs. For example, depending on the script system, if a style run occurs at the beginning or end of a line, extra space may not be added to the outer edge of the outermost glyph, whereas if a style run is interior to a line, all of the glyphs of the text may be treated the same: extra space is allocated to both sides of every glyph including those at either end of the style run.

The current implementations of simple script systems such as Roman and Cyrillic do not justify a line of text by changing the width of nonspace characters. Instead, they rely solely on the use of space characters: the same amount of extra width is added to (or subtracted from) every space whether the space is at the beginning or end of the line or interior to it.

numer

A point giving the numerator for the horizontal and vertical scaling factors.

Both numer and denom are point values: numer specifies the numerator for the horizontal and vertical scaling factors, and denom specifies the denominator for the horizontal and vertical scaling factors. Together, these values specify the scaling factors for the text: numer.v over denom.v gives the vertical scaling (height), and numer.h over denom.h gives the horizontal scaling factors (width). You need to specify values for numer and denom even if you are not scaling the text. For unscaled text, you can specify scaling factors of 1, 1.

denom

A point giving the denominator for the horizontal and vertical scaling factors.

function result: A number that represents the portion of the slop to be applied to the style run for which it is called.

DISCUSSION

You use PortionLine in formatting a line of justified text. It helps you determine how to distribute the slop for a line among its style runs. When you know the total slop for a line of text, you need to determine what portion of it to attribute to each style run. To do this, you call the PortionLine function once for each style run on the line. The PortionLine function computes the portion of extra space for a style run, taking into account the font, size, style, and scaling factors of the style run. It returns a number that represents the portion of the slop to be applied to the style run for which it is called. You use the value that PortionLine returns to determine the percentage of slop that you should attribute to a style run.

To determine the percentage of slop to allocate to each style run, you compute what percentage each portion is of the sum of all portions. To determine the actual slop value in pixels for each style run, you apply the percentage to the total slop value. The following steps summarize this process:

Call PortionLine for each style run on the line.
Add the returned values together.
Calculate the percentage of the slop value for each style run using the ratio of the value returned by PortionLine for that style run and the total of the values returned for all of the style runs on the line.
Calculate the number of pixels to be added to each style run by multiplying the percentage of the slop for each style run by the total number of pixels.

Be sure to pass the same values for styleRunPosition and the scaling factors (numer and denom) to PortionLine that you pass to any of the other justification functions for this style run.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.